PATHMac OS 8 and 9 Developer Documentation > Human Interface Toolbox > Window Manager >

Programming With the Mac OS 8.5 Window Manager

Window Proxy Icons

The Mac OS 8.5 Window Manager supports the display of a small icon in the title bar of document windows (next to the window title) that serves as a proxy for the document's icon in the Finder. This proxy icon appears and behaves the way the icon for the document does in the Finder. For example, the user can drag a document's proxy icon to move or copy the document file.

Additionally, the proxy icon is a source of visual feedback for the user on the current state of the document, such as whether the document window is a valid drag-and-drop target and whether the document has unsaved changes. Figure 1-2 shows a proxy icon in a window that contains a document with no unsaved changes.

Figure 1-2  Proxy icon in a window containing a document with no unsaved changes

The Mac OS 8.5 Window Manager provides the following functions for establishing proxy icons in your application's windows. See Supporting Window Proxy Icons for examples of how your application can provide proxy icon support in its document windows.

• SetWindowProxyFSSpec associates a file with a window.
• GetWindowProxyFSSpec obtains a file system specification structure for the file that is associated with a window.
• SetWindowProxyAlias associates a file with a window.
• GetWindowProxyAlias obtains an alias for the file that is associated with a window.
• SetWindowProxyCreatorAndType sets the proxy icon for a window that lacks an associated file.
• SetWindowProxyIcon overrides the default proxy icon for a window.
• GetWindowProxyIcon obtains a window's proxy icon.
• RemoveWindowProxy dissociates a file from a window.

Note that, in Figure 1-2 , the proxy icon is drawn in the enabled state to indicate that the file represented by the icon has no unsaved changes and that the user may therefore manipulate the icon and thereby the file itself. If a user drags a proxy icon to a folder, Finder window, the desktop, or another volume, the file represented by the proxy icon is moved or copied accordingly, as if the user had dragged the file's icon in the Finder.

The Mac OS 8.5 Window Manager provides the following functions for dragging proxy icons. See Tracking a Window Proxy Icon Drag for an example of how your application can call these functions.

• TrackWindowProxyDrag handles all aspects of the drag process when the user drags a proxy icon.
• TrackWindowProxyFromExistingDrag allows custom handling of the drag process when the user drags a proxy icon.
• BeginWindowProxyDrag creates the drag reference and the drag image when the user drags a proxy icon.
• EndWindowProxyDrag disposes of the drag reference when the user completes the drag of a proxy icon.

An application typically tracks the modification state of a document. A common reason to do so is to inform the user that they have made changes to the document which they might wish to save before closing the window.

When your application uses proxy icons, it should inform the Window Manager when a document has unsaved changes. When you do so, the Window Manager displays the document's proxy icon in a disabled state and prevents the user from dragging the proxy icon. Disabled proxy icons cannot be dragged because unsaved documents cannot be moved or copied in a manner predictable to the user. Figure 1-3 shows a proxy icon in a document window with unsaved changes.

IMPORTANT

The only time that a document's proxy icon should be disabled is when the document has unsaved changes. Your application should not disable the proxy icon at any other time.

Figure 1-3  Proxy icon in a window containing a document with unsaved changes

The Mac OS 8.5 Window Manager provides the following functions for accessing the modification state of a window. See Setting a Window's Modification State for an example of how your application can call these functions.

• SetWindowModified sets the modification state of the specified window.
• IsWindowModified obtains the modification state of the specified window.

When the user drags content that an application can accept into the content area of one of its windows, the structure region of the window, including the proxy icon, should become highlighted, as shown in Figure 1-4 . This gives visual feedback that the window is a valid destination for the content.

Figure 1-4  Proxy icon in a window that is a valid drag-and-drop target

The Mac OS 8.5 Window Manager provides the following function for indicating to the user whether a window is a valid drag-and-drop target:

• HiliteWindowFrameForDrag sets the highlight state of the window's structure region to reflect the window's validity as a drag-and-drop destination.

Figure 1-5 compares the various states of a proxy icon: enabled, for a document with no unsaved changes; disabled, for a document that does have unsaved changes; and highlighted, for when the document window is a valid destination for content that the user is dragging.

Figure 1-5  Proxy icon states